#ifndef __TBF_H__
#define __TBF_H__

/**
 * @def MAXTBF
 * @brief 令牌桶库最大容量（最大并发令牌桶实例数）
 */
#define MAXTBF	1024

/**
 * @brief 初始化令牌桶
 * @param cps 令牌生成速率（单位：令牌/秒）
 * @param burst 令牌桶容量上限（最大突发令牌数）
 * @return 令牌桶描述符（非负整数） 成功时返回有效描述符，
 *         失败返回-1（当超过MAXTBF或参数非法时）
 * 
 * @details 初始化并注册令牌桶实例到令牌桶库，返回该实例的索引描述符。
 *          令牌桶将按指定速率持续生成令牌直至达到容量上限。
 */
int tbf_init(int cps, int burst);

/**
 * @brief 尝试获取令牌
 * @param td 令牌桶描述符（由tbf_init返回）
 * @param ntoken 请求获取的令牌数量（必须为正整数）
 * @return 实际获取的令牌数量（可能小于请求值） 成功时返回实际获取的令牌数，
 *         失败返回-1（当描述符非法或系统错误时）
 * 
 * @note 当可用令牌不足时可能返回小于ntoken的值，需由调用方处理部分获取情况
 */
int tbf_fetch_token(int td, int ntoken);

/**
 * @brief 归还未使用的令牌
 * @param td 目标令牌桶描述符
 * @param ntoken 需归还的令牌数量（必须为非负整数）
 * @return 操作状态 成功返回0，
 *         失败返回-1（当描述符非法或归还数量超过初始burst值时）
 * 
 * @warning 归还令牌数不得超过初始burst值，否则视为无效操作
 */
int tbf_return_token(int td, int ntoken);

/**
 * @brief 销毁指定令牌桶实例
 * @param td 要销毁的令牌桶描述符
 * 
 * @details 释放令牌桶资源并从令牌桶库注销该实例。操作后描述符失效，
 *          再次使用将导致未定义行为。
 */
void tbf_destroy(int td);

/**
 * @brief 销毁所有令牌桶实例
 * 
 * @details 清空令牌桶库并释放所有资源。通常在程序终止前调用。
 */
void tbf_destroy_all(void);

#endif
